.\" Hey, Emacs! This is an -*- nroff -*- source file.
.\" Copyright (c) 2011 Tom Cocagne <tom.cocagne@gmail.com>
.\"
.\" Proccess this file with 
.\" groff -man -Tascii srp_admin.1
.\"
.TH srp_admin 1 "February 2011" "User Manuals"
.SH NAME 
srp_admin \- SRP Authentication database command line client
.SH SYNOPSIS
\fBsrp_admin\fR [\fB\fIGeneral Options\fB\fR] <\fB\fIcommand \fR...>
.SH DESCRIPTION
srp_admin is a command line interface for administering an SRP
Authentication database. The overall srp_admin command includes
multiple sub-commands which are described below. Unless otherwise
noted below, all of the sub-commands require database administration
privileges.  This utility will connect to the SRP server using either
the current user's credentials or the specified user's credentials (if
the -u option is used).  The password for the account will be
interactively queried prior to connecting.
.SH "GENERAL OPTIONS"
.TP
\fB-u \fIadmin_user\fB\fR
Connect as the specified administrative user instead of connecting
as the current user.
.TP
\fB-f \fIfilename\fB\fR
Configuration file. Defaults to /etc/srp_auth.conf
.TP
\fB-c \fIconfig_name\fB\fR
Use the specified configuration within the configuration file
instead of the default
.SH "COMMANDS"
.PP
The following commands are available:
.TP
\fBadd <new_username> [-l] [-a]\fR
Adds the new user to the SRP database. A password for the new user
will be queried interactively. If '-l' is present, the account will be
initially locked. If '-a' is present, the account will have
administrative privileges.
.TP
\fBremove <username>\fR
Removes the user from the SRP database.
.TP
\fBlist\fR
Lists all users in the database
.TP
\fBshow <username>\fR
Displays detailed information for the user.
.TP
\fBchange_password [username]\fR
Changes the password for the current user or the specified user. 
Non-administratvie users may change their own password with this
command.
.TP
\fBlock <username>\fR
Locks the user's account. All authentication attempts made on
locked accounts will fail.
.TP
\fBunlock <username>\fR
Unlocks the user's account.
.TP
\fBset_admin <username>\fR
Grants the user administrative privileges on the SRP database.
.TP
\fBunset_admin <username>\fR
Revokes the user's SRP database administration privileges.
.TP
\fBset_expiration <username> <time-specification>\fR
Sets the user's password expiration time to the specified value. Refer to
the
.B TIME SPECIFICATION FORMAT
section below for formatting options.
.TP
\fBget_public_info [server:port] [filename]\fR
Retrieves the server's public information including the required hash
algorithm, prime number size, and the server's binary, DER-encoded
public RSA key (if a filename to store the key in is provided). If the
optional "server:port" option is omitted, the server specified in the
configuration file will be queried.
.TP
\fBinit_host <server:port>[-c num_cached_credentials]\fR 
This command provides a simple means to configure the local
host for use with the specified SRP server. This command is purely
optional and serves only to automate the otherwise manual process of
setting up a default srp_auth configuration.

The command will create an /etc/srp_auth.conf file with the proper
settings for use with the specified SRP server and a copy of the SRP
server's public key will be stored in the /etc/srp_auth.d/default.der
file.  The -c option may be used to override the default number of
cached credentials used by the PAM plugin module (default is
10). Specifying a value of 0 will disable the use of the credential
cache. Otherwise a database for cached credentials will be created at
/var/run/srp_auth/cred_cache.db
 
.I NOTE: 
This command does
.B NOT
modify the PAM configuration files. The PAM
configuration must be manually edited for proper use of the srp_auth
module.  Please refer to the srp_auth(7) manual page for
instructions on modifying the PAM configuration to use the srp_auth
plugin module.

.TP
\fBcreate_credential_cache [file_name]\fR
Creates a file the PAM SRP authentication plugin module may use to
cache user credentials for offline use. The file will be created with
mode 0600. The owner, group, and file-permissions should be properly
configured before attempting to use the credential cache file with the
PAM plugin (similar to the /etc/shadow file). Failure to properly
protect the credential cache file could lead to system compromize. If no
file is specified, the default of /var/lib/srp_auth/cred_cache.db will
be used.
.TP
\fBcreate_credential_database [file_name] [-h <hash_type>] [-p <prime_size>]\fR 
This command interactively queries for the initial administrative username and
password then creates the database file for the SRP authentication
daemon. If no file name is specified, it will default to 
/var/lib/srp_auth/credentials.db The resulting file will have a mode of 
0600. This file should be readable and modifiable
by only by the SRP authentication daemon. Failure to properly protect
this file could lead to the compromize of any system relying on the
SRP authentication daemon. 

The database can be configured 
to use multiple length hash algorithms and prime numbers. Essentially, longer
hashes and prime numbers result in greater security at the cost of
increased computation time. The defaults of SHA1 hashes and 2048-bit
prime numbers strike a good balance. However, these parameters may be
tuned as follows:

  Available hash types:
      SHA1, SHA224, SHA256, SHA384, SHA512

  Available prime number sizes:
      1024, 2048, 4096, 8192
.SH "TIME SPECIFICATION FORMAT"
The time specification may take three forms:
.TP
\fBnow\fR
Immediately expires the user's password
.TP
\fBnever\fR
Prevents the users password from ever expiring
.TP
\fB<number><units>\fR
Sets the account to expire a number of units from
now. Acceptable units are:
.RS
.RS
.PD 0
.PP
.B s
- Seconds
.PP
.B n
- Minutes (note this is lower case N)
.PP
.B h
- Hours
.PP
.B d
- Days
.PP
.B m
- Months (note this is lower case M)
.PP
.B y
- Years
.RE
Examples:
    3d   - 3 days from now
    5n   - 5 Minutes from now
.RE
.PD
.SH AUTHOR
Tom Cocagne <tom.cocagne@gmail.com>
.SH "SEE ALSO"
.BR srp_auth.conf (5),
.BR srp_auth (7)
